fix(runtime): flush pending telemetry at process exit - #108

TL;DR

Normal process exit now flushes queued Langfuse spans and scores automatically.

Why

Short-lived tasks and one-off scripts could exit before SDK background workers delivered pending telemetry.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

Summary

Normal process exit now flushes pending spans and scores. Applications do not need to register their own at_exit callback. Explicit Langfuse.shutdown and Langfuse.reset! disable the pending callback for the current lifecycle.

The callback runs once and catches shutdown errors. The callback inherits the fork-safe synchronization from the base PR. This PR targets the fork-safety branch so the unsafe exit-only behavior cannot land first.

Change diagram

flowchart LR
    accTitle: Automatic telemetry flush during process exit
    accDescr: A normal process exit runs one SDK callback that flushes queued spans and scores without allowing errors to escape.
    E["Normal process exit"] --> H["Run one SDK callback"]
    H --> T["Flush pending spans"]
    H --> S["Flush pending scores"]
    H --> G["Catch shutdown errors"]
    X["Explicit SDK shutdown"] --> D["Disable pending callback"]

Verification

I ran the complete RSpec suite locally. All 1,581 examples passed. Line coverage was 96.51%.

I ran RuboCop against 101 files. RuboCop reported no offenses.

I ran a separate Ruby process with the SDK and did not call Langfuse.shutdown. The process exited normally. The exit callback delivered trace 93999b473b9b9d18d22d0e1537004e64 and its queued sdk-exit-hook score. The Langfuse CLI read back both records.

I did not test abrupt termination because SIGKILL cannot run process-exit callbacks. I did not preview the rendered Mermaid diagram in GitHub. I reviewed the Mermaid source and syntax locally.